Reading logs like prose

A log line is a sentence someone will read at three in the morning under the worst conditions of their working life. We write them like commit messages written like variable names.

Here is one I inherited: ERR_SYNC_2 tid=8842 st=3. It is precise, greppable and completely silent about what went wrong. To use it you need the source. At three in the morning you do not want the source, you want a sentence.

The rewrite

The replacement says: Sync gave up on tenant 8842 after 3 tries — the last response was a 502 from billing. It is longer. It costs a few more bytes per line, which at our volume rounds to nothing. It answers the next question before it is asked, which is the whole job.

The rule I use now: write the line as if the reader has never seen the code and cannot see it now. Name the thing that failed, what was tried, and what the other side said. Put the identifier in the sentence rather than in a suffix, because a suffix is a footnote and nobody reads footnotes at three in the morning.

What it costs

Structured fields still matter and I keep them — the sentence and the fields are not rivals. What changed is which one I write first. Fields are for the machine that aggregates. The sentence is for the person who has been woken up. We had spent years writing exclusively for the machine and then acting surprised that the on-call rotation was miserable.

Six months in, the clearest signal is that people now read the logs on purpose, when nothing is broken, the way you skim a diary. That never happened with the old ones.